home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Mac Game Programming Gurus / TricksOfTheMacGameProgrammingGurus.iso / More Source / C⁄C++ / E-Z Progress Bar 1.0a / How to use ProgressClass… < prev    next >
Text File  |  1995-03-14  |  5KB  |  123 lines
  1. Using the ProgressClass
  2.  
  3. • Remember to set the flag in your size resource to allow for background processing!
  4.  
  5. • What files you should include:
  6.     nclude ProgressClass.cp, ChiselClass.cp and Environ.cp in your project
  7.     include "ProgressClass.h" wherever you need to create a ProgressClass variable
  8.  
  9. • Options
  10.     Available options to choose from with the SetOptions command:
  11.         
  12.         default options: User can cancel, the progress bar's frame is chiseled in, the progress
  13.                         bar is chiseled, there is a generic gray background to the window, and
  14.                         a fine chisel surrounds the bar's frame
  15.                         
  16.         (Add or subtract these to add or remove; for example for all default options except
  17.         "fineChisel" type var.SetOptions(progressDefaults-fineChisel)
  18.         
  19.         void        SetOptions(short options=progressDefaults);
  20.  
  21.         progressDefaults    //    turns on all defaults
  22.         canCancel            //    toggles whether user can cancel the operation
  23.         chiselFrame            //    will chisel the progress bar's frame
  24.         grayBack            //    gray background for progress window?  Note: you can specify your
  25.                             //    own window color via SetWindowColor
  26.         chiselBar            //    will chisel the progress bar out if chosen
  27.         fineChisel            //    outlines the whole chisel frame with a fine chisel
  28.         
  29.     
  30.     When declaring your variable, you can set the options (note the default options are passed if
  31.     you don't specify any):
  32.     
  33.         ProgressClass(short options=progressDefaults);
  34.  
  35. • Configuring the ProgressClass
  36.  
  37.     While you don't technically need to do anything except declare an instance of the ProgressClass 
  38.     and show the window, you should give it some information so that it can work like a truly
  39.     integrated part.  
  40.     
  41.     • Menu IDs
  42.     Because it can handle all events received, letting you concentrate on coding your task,
  43.     you should pass it the ID number of the apple menu as well as your other menus so that it can
  44.     handle mouse down events effectively.  It will dim all of your menus if they are selected,
  45.     but allow items from the apple menu to be selected (except your about box - it will search until
  46.     it finds the line dividing your about box and any other items you have and only launch items in
  47.     the apple menu).  I have allowed for eight of your menus to be set in the class and dimmed.  If
  48.     you don't pass the IDs of your menus, they will not be deselected when the user clicks in the
  49.     menu bar.  All items will be returned to their previous state when either a) you hide the window
  50.     or b) the variable is destroyed
  51.  
  52.     void        SetAppleMenu(short appleID);
  53.     void        AddMenuNumber(short m1=0, short m2=0, short m3=0, short m4=0, short m5=0, short m6=0, short m7=0, short m8=0);
  54.  
  55.     • You can also change the progress bar's height (from its default 11 pixels), its width,
  56.     its color, and the empty color (the color behind the bar).
  57.  
  58.     void        SetBarHeight(short height);
  59.     void        SetBarWidth(short width);
  60.  
  61.     void        SetEmptyColor(RGBColor theColor);
  62.     void        SetBarColor(RGBColor theColor);
  63.     
  64.     • You can choose a different background color for the window.
  65.  
  66.     void        SetWindowColor(RGBColor theColor);
  67.     
  68.     • You should name the progress window and pass the class a string to post over the progress
  69.     bar (for example, "Sorting List…")
  70.     
  71.     void        SetTexts(Str255 windowTitle, Str255 paramText);
  72.     
  73.     • Finally, you can pass the resource ID of a custom button control to the class to use
  74.     instead of the Mac's default button
  75.     
  76.     void        SetControlID(short controlID);
  77.     
  78.  
  79.  
  80. • Controlling the Length of the Progress Bar
  81.  
  82.     To control the length of the progress bar, you can either set the minimum and maximum
  83.     values you will be using throughout your operation (if you're in a for loop, for example)
  84.     and pass the current value to SetBar, or you can pass a floating point value representing
  85.     what percent you have completed.  You can also update the string above the progress bar
  86.     when you update the value of the bar.
  87.  
  88.     void        SetMinMax(short min, short max);
  89.     void        SetBar(short current);
  90.     void        SetBar(short current, Str255 paramText);    
  91.     void        SetBar(float current);                        
  92.     void        SetBar(float current, Str255 paramText);
  93.  
  94.  
  95. • Receiving Events
  96.  
  97.     To make life easy on you, most events can be handled by the ProgressClass if you call the
  98.     ReceivedEvent(…) function on a regular basis.  Calling this function will allow the class
  99.     to update itself (so it should therefore be called at least once after you call ShowBarWindow())
  100.     and will inform you if you need to update/deactivate windows and whether the user cancelled or
  101.     not.  If ReceivedEvent(…) returns true, then you should examine its parameters.  Here's how
  102.     each event will be returned:
  103.     
  104.     UpdateEvents:
  105.         userCancel=0, deactivate=0, updateWindow=WindowPtr of window to be updated
  106.     ActivateEvents:
  107.         deactivate:
  108.             userCancel=0, deactivate=1, updateWindow=WindowPtr of window to be deactivated
  109.     User Cancelled:
  110.         userCancel=1, deactivate=0, updateWindow=nil
  111.  
  112.     Boolean        ReceivedEvent(Boolean *userCancel, Boolean *deactivate, WindowPtr *updateWindow);
  113.  
  114.  
  115. • Hiding and showing windows
  116.  
  117.     void        HideBarWindow();
  118.     void        ShowBarWindow();
  119.  
  120.  
  121. • If you have any other needs or desires for this class, or if you find bugs, please contact me
  122. at MaT101@aol.com.  Also, if you can tell me how to get a hold of the hilite color in the qd global
  123. var, let me know!